home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / manual-p / man_db-2.000 / man_db-2 / man_db-2.3.10 / README < prev    next >
Encoding:
Text File  |  1995-07-13  |  10.0 KB  |  253 lines
  1. README for the man_db manual pager suite, version 2.3.x
  2. =======================================================
  3.  
  4. Please read the man_db-manual, available in cat/PostScript/dvi formats,
  5. located at an FTP site carrying this package.  It contains configuration 
  6. details and other aspects of this manual pager suite that are not 
  7. duplicated or relevant here.
  8.  
  9. Read docs/INSTALL.autoconf for generic options to configure.
  10. Read docs/INSTALL.quick if you know all about man_db.
  11. Read docs/NEWS for visible changes since the last public release.
  12. Read docs/ChangeLog for details of recent source code changes.
  13. Read docs/ToDo for future plans.
  14.  
  15. This package _requires_ GNU make version 3.68 or newer to be used. 
  16. Other vendors' make programs will not work with the Makefiles in this 
  17. package due to extensive utilization of GNU make features.
  18.  
  19. The C source will require an ANSI C compiler. To generate dependencies 
  20. (only necessary if developing or source level debugging), a cpp that
  21. understands -M is required.
  22.  
  23.  
  24. Notice to users of man_db version 2.2 or 2.2.1 
  25. ==============================================
  26.  
  27. If you have stray-cats and created place-holders for them with `straycats'
  28. from the man_db-2.2 distribution, you must delete them before using
  29. man_db-2.3.  (straycats v2.2 with an option of `--delete-placeholders' will 
  30. do).  man_db-2.3 still provides support for stray-cats, but uses a database
  31. entry rather than a file system i-node to indicate their presence.
  32.  
  33. Obsoleted files include $(libdir)/makewhatis, /etc/manpath.config,
  34. $(bindir)/{getwhatis,makewhatis,straycats}, $(libdir)/globalman.*,
  35. any user localman.* databases and the manual pages: getwhatis, makewhatis
  36. and straycats all from section 8.  The other binaries: 
  37. $(bindir)/{man,mandb,manpath,apropos,whatis} and associated manual pages 
  38. may be replaced by this version depending upon install directories.
  39.  
  40.  
  41. Notice regarding current state of FSSTND (Linux/?BSD)
  42. =====================================================
  43.  
  44. The FSSTND is currently in a state of flux with respect to manual and
  45. cat page hierarchies.  As of July 13th, 1995, the last public release
  46. of the standard proposed the root of the manual page hierarchy as
  47. `/usr' and the root of the writable cat hierarchy as `/var/catman' for
  48. the purposes of man->cat filename translation.  As such, the following
  49. are defined in ./include/manconfig.h.in:
  50.  
  51. #define CAT_ROOT        "/var/catman"           /* required by fsstnd() */
  52. #define MAN_ROOT        "/usr"                  /* required by fsstnd() */
  53.  
  54. Should these locations change, simply define the paths accordingly and
  55. recompile.  Other FSSTND changes relating to man/cat paths will not be
  56. compatible with this version of man_db.
  57.                                                 
  58. INSTALL
  59. =======
  60.  
  61. Running configure.
  62.  
  63.     o READ `docs/INSTALL' regarding ./configure options
  64.  
  65.     o RUN `./configure --help' to see what --enable and --with
  66.       options may be useful.
  67.  
  68.     o RUN `./configure' with the appropriate options and environment
  69.       variable settings
  70.  
  71. BROWSE or EDIT the following files that are created by the configuration
  72. process.
  73.  
  74.     o `include/Defines' regarding general definitions used by all
  75.       Makefiles in the distribution
  76.  
  77.     o `include/manconfig.h' regarding paths to support programs,
  78.       the default section list and other specific definitions.
  79.  
  80.     o `include/comp_src.h' if the default compressor support is
  81.       inadequate for your requirements.  (usually .Z [compress], 
  82.       .z, .gz [gzip])
  83.  
  84. Running make.
  85.  
  86. configure will determine your system's ability to use native language
  87. support (NLS) message catalogues.  If support is available, running `make'
  88. with no target will display the available language identifiers.  To compile 
  89. man_db with no support for message catalogues, simply run `make' with a 
  90. target of `all'.  N.B. This is not related to man's ability to display NLS 
  91. manual pages, support for which is compiled in by default. 
  92.  
  93.     o RUN `make' to query nls languages on systems that support message
  94.       catalogues or `make all' to compile with the default English
  95.       messages only. 
  96.  
  97. If you ran `make' with no target and the compile did not begin, do one of 
  98. the following.
  99.  
  100.     o RUN `make nls=<your_choice>', `make nls=all' or `make nls=off'
  101.       which is equivalent to `make all'.
  102.  
  103. Sort out the man_db configuration file.
  104.  
  105.     o RUN `./src/man -l man/man5/manpath.5' from the root of this
  106.       distribution to read the man_db configuration file details.
  107.  
  108.     o EDIT `./src/man_db.config' to your local requirements.
  109.  
  110. Install the package.
  111.  
  112.     o (gain superuser privileges for the rest of the steps)
  113.  
  114.     o RUN `make install' to install the utilities and English manual 
  115.       pages.
  116.  
  117. The following command is required if you elected to compile the package
  118. without support for message catalogues but would like to install native
  119. language manual page translations.
  120.  
  121.     o RUN `make man targets=install nls=<your_choice>' to install
  122.       translations of the standard English manual pages 
  123.  
  124. Initialise the `index' databases for all manpaths marked as global in the
  125. man_db configuration file.
  126.  
  127.     o RUN `mandb' (This step is equivalent to running straycats and 
  128.       makewhatis too).
  129.  
  130. The following steps are optional / dependent on local conventions.
  131.  
  132.     o ACKNOWLEDGE any warnings emitted by mandb. Bogus manual pages
  133.       are not included in the database and may be a waste of space.
  134.       Those pages without correctly formatted `whatis' lines are
  135.       included, but will have a whatis entry of "(unknown)"
  136.  
  137.     o CD tools and RUN `mkcatdirs -t' to see if you have all of the
  138.       required cat directories.  `mkcatdirs' without an option will 
  139.       display a usage message.
  140.  
  141.     o CD tools and RUN `checkman' with an argument of colon separated
  142.       manual page hierarchies to cross check for duplicated manual
  143.       pages.  If no argument is given, your default $MANPATH will be
  144.       used.
  145.     
  146.       The output of checkman may be piped into a file and used as an
  147.       argument to `rm', the `is newer than' messages are directed to 
  148.       standard error.  e.g. `checkman > dups'
  149.  
  150.       If you are confident that the duplicates found are indeed 
  151.       duplicates, you can back them up and delete them to save space.
  152.  
  153.       At this point, running checkman again may yield further duplicates 
  154.       that were ignored the first time.
  155.  
  156.     o RUN `catman' with appropriate options to create any/all cat files
  157.       that you would like pre-formatted.
  158.  
  159.  
  160. Multiple build directories
  161. ==========================
  162.  
  163. It is possible to build man_db-2.3 in a directory other than the directory
  164. containing this file (and all of the program sources).  This is particularly
  165. useful if compiling on multiple architectures or testing various
  166. configuration options as only a single copy of the sources is required.
  167.  
  168. To enable this support, simply change directory to where you would like to
  169. build the package and run the configure program in this directory 
  170. *from there*.  Further information about this support can be found in the 
  171. generic install document `docs/INSTALL'
  172.  
  173.  
  174. Makefile targets and variables
  175. ==============================
  176.  
  177. The standard GNU Makefile targets: all, install, uninstall, mostlyclean,
  178. clean, distclean, realclean and TAGS are available in every Makefile-
  179. supported directory.  In addition, the master Makefile has the targets:
  180. update (update any configuration files whose source has changed) and dist
  181. (create a compressed and tarred distribution file).
  182.  
  183. During the configuration process, `configure' sets the installation
  184. variables, `prefix' and `exec_prefix'.  These are then used to form other
  185. variables such as `bindir' and `sysconfdir'.  To change any of these or 
  186. other standard GNU install variables dynamically, issue the `make' command 
  187. with variable expressions as arguments, eg. `make prefix=/usr/local/packages'
  188.  
  189. N.B. If prefix=/usr (either statically or dynamically), then sysconfdir=/etc
  190. instead of the usual $(prefix)/etc.  To force sysconfdir to be /usr/etc, set
  191. it on the make command line.
  192.  
  193.  
  194. Default preprocessors
  195. =====================
  196.  
  197. man_db uses a manual page directed preprocessor system, that is, each manual
  198. page may request preprocessing by a selection of preprocessors.  Some
  199. systems' manual pages do not come with this information built in.  In such
  200. circumstances, it is advisable to set a default list of preprocessors that
  201. each manual page should be passed through, so that those requiring special
  202. processing are readable.  To achieve this, set DEFAULT_MANROFFSEQ (found in
  203. include/manconfig.h) to the appropriate preprocessor string, after running
  204. configure, but prior to compilation.  This is not necessary for the
  205. following systems whose default preprocessing requirements are known.
  206.  
  207.   Known not to require DEFAULT_MANROFFSEQ:
  208.     Linux, SunOS
  209.   Known to require #define DEFAULT_MANROFFSEQ "t":
  210.     Ultrix
  211.   Known to require #define DEFAULT_MANROFFSEQ "te":
  212.     HP-UX, OSF/1
  213.  
  214. If unsure of the default preprocessors required by a system, the standard
  215. system's man(1) manual page may provide an answer. 
  216.  
  217.  
  218. System specific notes
  219. =====================
  220.  
  221. Linux
  222.  
  223.     o Public released C library distributions prior to 4.5.26 contain 
  224.       no Berkeley DB interface routines and an old gdbm implementation. 
  225.       It is advisable to either install a recent version of gdbm (v1.6+) 
  226.       or the Berkeley DB library (v1.79+) to gain enhanced performance.
  227.  
  228.     o C library distribution 4.6.20 contains a bug that requires -static 
  229.       to be used as a linker option if -g and -ldb are also used.  If 
  230.       not, programs linked with the db library will cause a segmentation
  231.       violation on startup.
  232.  
  233.     o C library distribution 4.6.27 contains a bug that causes links
  234.       with -ldb to fail completely if -g is used without -static.  As 
  235.       such, configure will automatically choose gdbm routines found 
  236.       in the gdbm library if $CFLAGS contains -g without -static at the 
  237.       time of running configure.
  238.  
  239.     o The recommended ./configure command:
  240.  
  241.         CFLAGS='-O2 -fomit-frame-pointer' ./configure --prefix=/usr
  242.  
  243.  
  244. Ultrix-4.3a
  245.  
  246.     o When compiled for BSD environment, each running `man' increases
  247.       the system load as reported by uptime(1) by one.  The reason for
  248.       this behaviour is currently unknown, but the load increase does
  249.       *not* reflect actual resource usage.  To avoid it, compile for
  250.       POSIX environment:
  251.  
  252.         CC='cc -YPOSIX' ./configure
  253.